Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Window, button, browse, and frame definitions

The next section is labeled Control Definitions. These are definitions for the objects in your window.

Defining a handle variable for the window

First is a definition for the window itself, or rather for a handle used to point to the window’s definition:

DEFINE VAR CustWin AS WIDGET-HANDLE NO-UNDO.

There are a couple of things to note about this statement before you examine what a handle really does:

You can see that the AppBuilder has abbreviated the keyword VARIABLE to VAR. You can abbreviate many Progress 4GL keywords in this way, but you cannot use arbitrary abbreviations. That is, each keyword definition in the language also defines the acceptable abbreviation of the keyword. If you want to confirm the minimum abbreviation for a keyword or find out the kind of statements in which it is used, you can always look it up in the Keyword Index in OpenEdge Development: Progress 4GL Reference . Not all keywords have abbreviations. You should generally not abbreviate any keywords. Typing keywords in full eliminates any chance of a conflict with a future keyword that starts the same way, and generally makes your code more readable. As described in the "Using the Intelligent Edit Control and its shortcuts" section, the Edit Control provides aliases for you to eliminate manually typing many of them in full.
The variable CustWin is defined as a WIDGET-HANDLE. The term widget applies to all sorts of things, including visual objects such as fields and buttons, as well as other things that can have handles, including queries and even procedures themselves. WIDGET-HANDLE is a synonym for the keyword HANDLE, because a single Progress data type accommodates all these different kinds of objects. Since there is really just one HANDLE data type, and since it is used for more than just objects that you might consider widgets, this book always uses the keyword HANDLE.

In the "Creating the window" section, you’ll look a little more about what the handle does when you get to the code that uses it to create the window.

Defining a button

Next is another kind of DEFINE statement. This one defines not a variable, but the first of your buttons:

DEFINE BUTTON BtnFirst LABEL "First" SIZE 15 BY 1.14.

There is a separate DEFINE statement for each different type of object you can have in your application. You can learn all the particular attributes you can set for each kind of object from the OpenEdge Development: Progress 4GL Reference or the online help, but they’re similar in form. The DEFINE statement first names the object (BtnFirst in this case) and then has a list of whatever attributes you want to define for the object and their values. In this case the AppBuilder has defined the button’s LABEL to be First, because this is what you set it to in the design window. The SIZE is a standard size the AppBuilder defaults, which you can change by resizing the button in the design window.

The following three statements are the definitions for the other three buttons in the window.

Defining a query

After the DEFINE BUTTON statement, the next statements define the two queries your procedure uses:

DEFINE QUERY OrderBrowse FOR Order SCROLLING. DEFINE QUERY CustQuery FOR Customer SCROLLING.

These statements define the query objects that your code later opens using the specific WHERE clause you defined in the Query Builder. The Order query got its name by default from the browse that displays its data, which you’ll see next. The Customer query got its name from the frame it’s in. You’ll learn more about queries in Chapter 10, " Using Queries."

Defining a browse

Next is the statement to define your Order browse:

DEFINE BROWSE OrderBrowse QUERY OrderBrowse NO-LOCK DISPLAY Order.Ordernum FORMAT "zzzzzzzzz9":U Order.OrderDate FORMAT "99/99/99":U Order.PromiseDate FORMAT "99/99/99":U Order.ShipDate FORMAT "99/99/9999":U Order.PO FORMAT "x(20)":U WITH NO-ROW-MARKERS SEPARATORS SIZE 65 BY 6.67 ROW-HEIGHT-CHARS .57 EXPANDABLE.

This code first names the query the browse is defined for, and then the list of fields to display, along with their formats. Finally there’s a list of attributes for the browse itself, in a phrase starting with the keyword WITH. You can set these and other attributes in the Browse property sheet you looked at in the "Using property sheets" section.

Defining a frame

Next is a section marked Frame Definitions, where the window’s one frame is defined:

DEFINE FRAME CustQuery BtnFirst AT ROW 1.48 COL 8 BtnNext AT ROW 1.48 COL 24.6 BtnPrev AT ROW 1.48 COL 41.2 BtnLast AT ROW 1.48 COL 58 Customer.CustNum AT ROW 3.38 COL 13.4 COLON-ALIGNED VIEW-AS FILL-IN SIZE 9 BY 1 Customer.Name AT ROW 3.38 COL 37 COLON-ALIGNED VIEW-AS FILL-IN SIZE 32 BY 1 Customer.Address AT ROW 4.57 COL 13 COLON-ALIGNED VIEW-AS FILL-IN SIZE 37 BY 1 Customer.City AT ROW 5.76 COL 13 COLON-ALIGNED VIEW-AS FILL-IN SIZE 27 BY 1 Customer.State AT ROW 5.76 COL 47 COLON-ALIGNED VIEW-AS FILL-IN SIZE 22 BY 1 OrderBrowse AT ROW 7.67 COL 13 WITH 1 DOWN NO-BOX KEEP-TAB-ORDER OVERLAY SIDE-LABELS NO-UNDERLINE THREE-D AT COL 1 ROW 1 SIZE 86 BY 13.67.

Here the code defines the position of each object in the frame. The exact position of the objects depends on how you laid them out in the design window. The four buttons are all at row position 1.48, counting in full character units.

Next come the fields from the Customer table. There are no DEFINE statements for these because the field definitions are taken automatically from the Data Dictionary definitions for the Customer fields.

Then the frame definition places the browse control at column 13 of row 7.67.

Finally, the frame definition has its own WITH clause, where it sets the following frame attributes:

1 DOWN — You’ll remember from Chapter 2, "Using Basic 4GL Constructs," that the kind of Progress frame you get from a FOR EACH block with a DISPLAY statement in it is a down frame that displays multiple records in a report-like format. Frames in a graphical application are typically one down frames, which display only one instance of the objects defined for the frame. In this case, the browse control is a single GUI object that takes the place of the multi-line down frame in the older interface style that’s designed for character terminals.
NO-BOX, OVERLAY, NO-UNDERLINE, THREE-D — These all define various visual characteristics of the frame and are self-explanatory.
KEEP-TAB-ORDER — This attribute keeps language statements such as the ENABLE statement you saw in enable_UI from changing the tab order of the fields.
AT COL 1 ROW 1 — This position is relative to the window the frame is in. The objects in the frame are positioned relative to the frame (their container), and the frame is positioned relative to its container (the window).
SIZE 86 BY 13.67 — This is the size of the whole frame in characters.

For more information on any of the frame attributes, see their descriptions under the Frame Phrase entry of the OpenEdge Development: Progress 4GL Reference .

Following the Frame Definition section are the Procedure Settings, which are specially formatted comments with information the AppBuilder uses internally. You should never edit special sections like this one.